.TH "NETCONF Event Notifications" 3 "Fri Apr 15 2016" "Version 0.10.0-146_trunk" "libnetconf" \" -*- nroff -*-
.ad l
.nh
.SH NAME
NETCONF Event Notifications \- 
.PP
libnetconf's implementation of NETCONF asynchronous message delivery as defined in RFC 5277\&.  

.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct nc_msg \fBnc_ntf\fP"
.br
.RI "\fIEvent notification message\&. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBNCNTF_EVENT\fP { \fBNCNTF_ERROR\fP = -1, \fBNCNTF_GENERIC\fP = 0, \fBNCNTF_REPLAY_COMPLETE\fP = 1, \fBNCNTF_NTF_COMPLETE\fP = 2, \fBNCNTF_BASE_CFG_CHANGE\fP = 3, \fBNCNTF_BASE_CPBLT_CHANGE\fP = 4, \fBNCNTF_BASE_SESSION_START\fP = 5, \fBNCNTF_BASE_SESSION_END\fP = 6, \fBNCNTF_BASE_CONFIRMED_COMMIT\fP = 7 }"
.br
.RI "\fIEnumeration of supported NETCONF event notifications\&. \fP"
.ti -1c
.RI "enum \fBNCNTF_EVENT_BY\fP { \fBNCNTF_EVENT_BY_SERVER\fP, \fBNCNTF_EVENT_BY_USER\fP }"
.br
.RI "\fIEnumeration of the possible source of events\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBnc_rpc\fP * \fBnc_rpc_subscribe\fP (const char *stream, const struct nc_filter *filter, const time_t *start, const time_t *stop)"
.br
.RI "\fICreate <create-subsciption> NETCONF rpc message\&. \fP"
.ti -1c
.RI "\fBNC_MSG_TYPE\fP \fBnc_session_recv_notif\fP (struct nc_session *session, int timeout, \fBnc_ntf\fP **ntf)"
.br
.RI "\fIReceive a <notification> message from the specified NETCONF session\&. This function is supposed to be performed only by NETCONF clients\&. \fP"
.ti -1c
.RI "int \fBnc_session_send_notif\fP (struct nc_session *session, const \fBnc_ntf\fP *ntf)"
.br
.RI "\fISend <notification> message from server to client\&. \fP"
.ti -1c
.RI "long long int \fBncntf_dispatch_receive\fP (struct nc_session *session, void(*process_ntf)(time_t eventtime, const char *content))"
.br
.RI "\fISubscribe for receiving notifications from the given session according to parameters in the given subscribtion RPC\&. Received notifications are processed by the given process_ntf callback function\&. Functions stops when the final notification <notificationComplete> is received or when the session is terminated\&. \fP"
.ti -1c
.RI "long long int \fBncntf_dispatch_send\fP (struct nc_session *session, const \fBnc_rpc\fP *subscribe_rpc)"
.br
.RI "\fIStart sending notifications according to the given <create-subscription> NETCONF RPC request\&. All events from the specified stream are processed and sent to the client until the stop time is reached or until the session is terminated\&. \fP"
.ti -1c
.RI "int \fBncntf_event_new\fP (time_t etime, \fBNCNTF_EVENT\fP event,\&.\&.\&.)"
.br
.RI "\fIStore a new event in the specified stream\&. Parameters are specific for different events\&. \fP"
.ti -1c
.RI "\fBnc_ntf\fP * \fBncntf_notif_create\fP (time_t event_time, const char *content)"
.br
.RI "\fICreate a new <notification> message with the given eventTime and content\&. \fP"
.ti -1c
.RI "void \fBncntf_notif_free\fP (\fBnc_ntf\fP *ntf)"
.br
.RI "\fIFree the notification message\&. \fP"
.ti -1c
.RI "char * \fBncntf_notif_get_content\fP (const \fBnc_ntf\fP *notif)"
.br
.RI "\fIGet description of the event reported in the notification message\&. \fP"
.ti -1c
.RI "time_t \fBncntf_notif_get_time\fP (const \fBnc_ntf\fP *notif)"
.br
.RI "\fIGet Time of the event reported in the notification message\&. \fP"
.ti -1c
.RI "\fBNCNTF_EVENT\fP \fBncntf_notif_get_type\fP (const \fBnc_ntf\fP *notif)"
.br
.RI "\fIGet a specific notification type\&. \fP"
.ti -1c
.RI "int \fBncntf_session_get_active_subscription\fP (struct nc_session *session)"
.br
.RI "\fICheck if a session has an active notification subscription\&. \fP"
.ti -1c
.RI "char * \fBncntf_status\fP (void)"
.br
.RI "\fIGet the status data in xml form describing the currently used streams\&. \fP"
.ti -1c
.RI "int \fBncntf_stream_allow_events\fP (const char *stream, const char *event)"
.br
.RI "\fISet the rule to allow logging of the specified event on the given Notification stream\&. \fP"
.ti -1c
.RI "int \fBncntf_stream_info\fP (const char *stream, char **desc, char **start)"
.br
.RI "\fIGet some more details about the specified NETCONF event notifications stream\&. \fP"
.ti -1c
.RI "int \fBncntf_stream_isavailable\fP (const char *name)"
.br
.RI "\fITest if the given stream is already created and available\&. \fP"
.ti -1c
.RI "void \fBncntf_stream_iter_finish\fP (const char *stream)"
.br
.RI "\fIClean all the structures used for iteration in the specified stream\&. This function must be called as a closing function to nc_ntf_stream_iter_start() \fP"
.ti -1c
.RI "char * \fBncntf_stream_iter_next\fP (const char *stream, time_t start, time_t stop, time_t *event_time)"
.br
.RI "\fIPop the next event record from the stream file\&. The iteration must be started by nc_ntf_stream_iter_start() function\&. \fP"
.ti -1c
.RI "void \fBncntf_stream_iter_start\fP (const char *stream)"
.br
.RI "\fIStart iteration on the events in the specified stream file\&. Iteration starts on the first event in the first part of the stream file\&. \fP"
.ti -1c
.RI "char ** \fBncntf_stream_list\fP (void)"
.br
.RI "\fIGet the list of NETCONF event notifications streams\&. \fP"
.ti -1c
.RI "int \fBncntf_stream_new\fP (const char *name, const char *desc, int replay)"
.br
.RI "\fICreate a new NETCONF event stream\&. \fP"
.ti -1c
.RI "\fBnc_reply\fP * \fBncntf_subscription_check\fP (const \fBnc_rpc\fP *subscribe_rpc)"
.br
.RI "\fICheck validity of <create-subscription> message\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
libnetconf's implementation of NETCONF asynchronous message delivery as defined in RFC 5277\&. 


.SH "Typedef Documentation"
.PP 
.SS "typedef struct nc_msg \fBnc_ntf\fP"

.PP
Event notification message\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBNCNTF_EVENT\fP"

.PP
Enumeration of supported NETCONF event notifications\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINCNTF_ERROR \fP\fP
error return code 
.TP
\fB\fINCNTF_GENERIC \fP\fP
a generic notification not directly supported by libnetconf 
.TP
\fB\fINCNTF_REPLAY_COMPLETE \fP\fP
<replayComplete> notification announcing the end of Replaying the stream 
.TP
\fB\fINCNTF_NTF_COMPLETE \fP\fP
<notificationComplete> notification announcing the end of Notification stream 
.TP
\fB\fINCNTF_BASE_CFG_CHANGE \fP\fP
netconf-config-change (RFC 6470) 
.TP
\fB\fINCNTF_BASE_CPBLT_CHANGE \fP\fP
netconf-capability-change (RFC 6470) 
.TP
\fB\fINCNTF_BASE_SESSION_START \fP\fP
netconf-session-start (RFC 6470) 
.TP
\fB\fINCNTF_BASE_SESSION_END \fP\fP
netconf-session-end (RFC 6470) 
.TP
\fB\fINCNTF_BASE_CONFIRMED_COMMIT \fP\fP
netconf-configrmed-commit (RFC 6470) 
.SS "enum \fBNCNTF_EVENT_BY\fP"

.PP
Enumeration of the possible source of events\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fINCNTF_EVENT_BY_SERVER \fP\fP
event is caused by a server 
.TP
\fB\fINCNTF_EVENT_BY_USER \fP\fP
event is caused by the user's action 
.SH "Function Documentation"
.PP 
.SS "\fBnc_rpc\fP* nc_rpc_subscribe (const char *stream, const struct nc_filter *filter, const time_t *start, const time_t *stop)"

.PP
Create <create-subsciption> NETCONF rpc message\&. Detailed description of this operation can be found in RFC 5277, section 2\&.1\&.1\&.
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the stream of events that is of interest\&. Optional parameter (NULL is accepted), if not specified, the default NETCONF stream is subscribed\&. 
.br
\fIfilter\fP Specify the subset of all possible events to be received\&. Optional parameter (NULL is accepted)\&. 
.br
\fIstart\fP Start time to trigger the replay feature from the specified time\&. Optional parameter (NULL is accepted)\&. Format of the date is of the type dateTime according to RFC 3339\&. 
.br
\fIstop\fP Stop time to stop the replay of event notifications\&. Optional parameter (NULL is accepted)\&. Format of the date is of the type dateTime according to RFC 3339\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Created rpc message\&. 
.RE
.PP

.SS "\fBNC_MSG_TYPE\fP nc_session_recv_notif (struct nc_session *session, inttimeout, \fBnc_ntf\fP **ntf)"

.PP
Receive a <notification> message from the specified NETCONF session\&. This function is supposed to be performed only by NETCONF clients\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session to use\&. 
.br
\fItimeout\fP Timeout in microseconds, -1 for infinite timeout, 0 for non-blocking 
.br
\fIntf\fP Received <notification> message 
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNC_MSG_NOTIFICATION\fP - success, *ntf points to the received <notification>
.IP "\(bu" 2
\fBNC_MSG_UNKNOWN\fP - error occurred
.IP "\(bu" 2
\fBNC_MSG_REPLY\fP - <rpc-reply> to some request received and enqueued to the internal queue until the \fBnc_session_recv_reply()\fP function is called\&. Caller is supposed to repeat the function call to receive another <notification> message\&.
.IP "\(bu" 2
\fBNC_MSG_WOULDBLOCK\fP - receiving timeouted without any received message\&. 
.PP
.RE
.PP

.SS "int nc_session_send_notif (struct nc_session *session, const \fBnc_ntf\fP *ntf)"

.PP
Send <notification> message from server to client\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session to use\&. 
.br
\fIntf\fP <notification> message to send\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success,
.br
 non-zero on error\&. 
.RE
.PP

.SS "long long int ncntf_dispatch_receive (struct nc_session *session, void(*)(time_t eventtime, const char *content)process_ntf)"

.PP
Subscribe for receiving notifications from the given session according to parameters in the given subscribtion RPC\&. Received notifications are processed by the given process_ntf callback function\&. Functions stops when the final notification <notificationComplete> is received or when the session is terminated\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session where the notifications will be sent\&. 
.br
\fIprocess_ntf\fP Callback function to process content of the notification\&. If NULL, content of the notification is printed on stdout\&.
.RE
.PP
\fBReturns:\fP
.RS 4
number of received notifications, -1 on error\&. 
.RE
.PP

.SS "long long int ncntf_dispatch_send (struct nc_session *session, const \fBnc_rpc\fP *subscribe_rpc)"

.PP
Start sending notifications according to the given <create-subscription> NETCONF RPC request\&. All events from the specified stream are processed and sent to the client until the stop time is reached or until the session is terminated\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session where the notifications will be sent\&. 
.br
\fIsubscribe_rpc\fP <create-subscription> RPC, if any other RPC is given, -1 is returned\&.
.RE
.PP
\fBReturns:\fP
.RS 4
number of sent notifications (including 0), -1 on error\&. 
.RE
.PP

.SS "int ncntf_event_new (time_tetime, \fBNCNTF_EVENT\fPevent, \&.\&.\&.)"

.PP
Store a new event in the specified stream\&. Parameters are specific for different events\&. 
.SS "Event parameters:"
.PP
.IP "\(bu" 2
\fBNCNTF_GENERIC\fP
.IP "  \(bu" 4
\fBconst char* content\fP Content of the notification as defined in RFC 5277\&. eventTime is added automatically\&. The string should be XML-formatted\&.
.PP

.IP "\(bu" 2
\fBNCNTF_BASE_CFG_CHANGE\fP
.IP "  \(bu" 4
\fBNC_DATASTORE\fP \fBdatastore\fP Specify which datastore has changed\&.
.IP "  \(bu" 4
\fBNCNTF_EVENT_BY\fP \fBchanged_by\fP Specify the source of the change\&.
.IP "    \(bu" 6
If the value is set to \fBNCNTF_EVENT_BY_USER\fP, the following parameter is required:
.PP

.IP "  \(bu" 4
\fBconst struct nc_session* session\fP Session that required the configuration change\&.
.PP

.IP "\(bu" 2
\fBNCNTF_BASE_CPBLT_CHANGE\fP
.IP "  \(bu" 4
\fBconst struct nc_cpblts* old\fP Old list of capabilities\&.
.IP "  \(bu" 4
\fBconst struct nc_cpblts* new\fP New list of capabilities\&.
.IP "  \(bu" 4
\fBNCNTF_EVENT_BY\fP \fBchanged_by\fP Specify the source of the change\&.
.IP "    \(bu" 6
If the value is set to \fBNCNTF_EVENT_BY_USER\fP, the following parameter is required:
.PP

.IP "  \(bu" 4
\fBconst struct nc_session* session\fP Session that required the configuration change\&.
.PP

.IP "\(bu" 2
\fBNCNTF_BASE_SESSION_START\fP
.IP "  \(bu" 4
\fBconst struct nc_session* session\fP Started session (\fBNC_SESSION_STATUS_DUMMY\fP session is also allowed)\&.
.PP

.IP "\(bu" 2
\fBNCNTF_BASE_SESSION_END\fP
.IP "  \(bu" 4
\fBconst struct nc_session* session\fP Finished session (\fBNC_SESSION_STATUS_DUMMY\fP session is also allowed)\&.
.IP "  \(bu" 4
\fBNC_SESSION_TERM_REASON\fP \fBreason\fP Session termination reason\&.
.IP "    \(bu" 6
If the value is set to \fBNC_SESSION_TERM_KILLED\fP, the following parameter is required\&.
.PP

.IP "  \(bu" 4
\fBconst char* killed-by-sid\fP The ID of the session that directly caused the session termination\&. If the session was terminated by a non-NETCONF process unknown to the server, use NULL as the value\&.
.PP

.PP
.PP
.SS "Examples:"
.PP
.IP "\(bu" 2
ncntf_event_new(-1, NCNTF_GENERIC, '<event>something happened</event>');
.IP "\(bu" 2
ncntf_event_new(-1, NCNTF_BASE_CFG_CHANGE, NC_DATASTORE_RUNNING, NCNTF_EVENT_BY_USER, my_session);
.IP "\(bu" 2
ncntf_event_new(-1, NCNTF_BASE_CPBLT_CHANGE, old_cpblts, new_cpblts, NCNTF_EVENT_BY_SERVER);
.IP "\(bu" 2
ncntf_event_new(-1, NCNTF_BASE_SESSION_START, my_session);
.IP "\(bu" 2
ncntf_event_new(-1, NCNTF_BASE_SESSION_END, my_session, NC_SESSION_TERM_KILLED, '123456');
.PP
.PP
\fBParameters:\fP
.RS 4
\fIetime\fP Time of the event, if set to -1, the current time is used\&. 
.br
\fIevent\fP Event type to distinguish the following parameters\&. 
.br
\fI\&.\&.\&.\fP Specific parameters for different event types as described above\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 for success, non-zero value else\&. 
.RE
.PP

.SS "\fBnc_ntf\fP* ncntf_notif_create (time_tevent_time, const char *content)"

.PP
Create a new <notification> message with the given eventTime and content\&. 
.PP
\fBParameters:\fP
.RS 4
\fIevent_time\fP Time of the event\&. 
.br
\fIcontent\fP Description of the event in the XML form\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Created notification message\&. 
.RE
.PP

.SS "void ncntf_notif_free (\fBnc_ntf\fP *ntf)"

.PP
Free the notification message\&. 
.PP
\fBParameters:\fP
.RS 4
\fIntf\fP notification message to free\&. 
.RE
.PP

.SS "char* ncntf_notif_get_content (const \fBnc_ntf\fP *notif)"

.PP
Get description of the event reported in the notification message\&. 
.PP
\fBParameters:\fP
.RS 4
\fInotif\fP Notification message\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Content of the event description (serialized XML)\&. 
.RE
.PP

.SS "time_t ncntf_notif_get_time (const \fBnc_ntf\fP *notif)"

.PP
Get Time of the event reported in the notification message\&. 
.PP
\fBParameters:\fP
.RS 4
\fInotif\fP Notification message\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Time of the event (as number of seconds since the epoch)\&. 
.RE
.PP

.SS "\fBNCNTF_EVENT\fP ncntf_notif_get_type (const \fBnc_ntf\fP *notif)"

.PP
Get a specific notification type\&. 
.PP
\fBParameters:\fP
.RS 4
\fInotif\fP Notification message to explore\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The same types as for \fBncntf_event_new()\fP can be returned\&. If the notification is unknown, the \fBNCNTF_GENERIC\fP is returned\&. 
.RE
.PP

.SS "int ncntf_session_get_active_subscription (struct nc_session *session)"

.PP
Check if a session has an active notification subscription\&. 
.PP
\fBParameters:\fP
.RS 4
\fIsession\fP NETCONF session to check\&.
.RE
.PP
\fBReturns:\fP
.RS 4
0 if there is no active subscription, non-0 otherwise\&. 
.RE
.PP

.SS "char* ncntf_status (void)"

.PP
Get the status data in xml form describing the currently used streams\&. 
.PP
\fBReturns:\fP
.RS 4
Text containing streams status data in xml form (urn:ietf:params:xml:ns:netmod:notification in RFC 5277)\&. 
.RE
.PP

.SS "int ncntf_stream_allow_events (const char *stream, const char *event)"

.PP
Set the rule to allow logging of the specified event on the given Notification stream\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the stream where to allow event logging 
.br
\fIevent\fP Name of the event which to allow on the given stream 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error 
.RE
.PP

.SS "int ncntf_stream_info (const char *stream, char **desc, char **start)"

.PP
Get some more details about the specified NETCONF event notifications stream\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the stream\&. 
.br
\fIdesc\fP Pointer to a description string is returned\&. 
.br
\fIstart\fP Pointer to a time string of the stream start time is returned\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero on error (desc and start are not returned in such a case)\&. 
.RE
.PP

.SS "int ncntf_stream_isavailable (const char *name)"

.PP
Test if the given stream is already created and available\&. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP Name of the stream to check\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 - the stream is not present,
.br
1 - the stream is present 
.RE
.PP

.SS "void ncntf_stream_iter_finish (const char *stream)"

.PP
Clean all the structures used for iteration in the specified stream\&. This function must be called as a closing function to nc_ntf_stream_iter_start() 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the iterated stream\&. 
.RE
.PP

.SS "char* ncntf_stream_iter_next (const char *stream, time_tstart, time_tstop, time_t *event_time)"

.PP
Pop the next event record from the stream file\&. The iteration must be started by nc_ntf_stream_iter_start() function\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the stream to iterate\&. 
.br
\fIstart\fP Time of the first event the caller is interested in\&. 
.br
\fIstop\fP Time of the last event the caller is interested in\&. 
.br
\fIevent_time\fP Time of the returned event, NULL if caller does not care\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Content of the next event in the stream\&. 
.RE
.PP

.SS "void ncntf_stream_iter_start (const char *stream)"

.PP
Start iteration on the events in the specified stream file\&. Iteration starts on the first event in the first part of the stream file\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP Name of the stream to iterate\&. 
.RE
.PP

.SS "char** ncntf_stream_list (void)"

.PP
Get the list of NETCONF event notifications streams\&. 
.PP
\fBReturns:\fP
.RS 4
NULL terminated list of stream names\&. It is up to the caller to free the list 
.RE
.PP

.SS "int ncntf_stream_new (const char *name, const char *desc, intreplay)"

.PP
Create a new NETCONF event stream\&. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP Name of the stream\&. 
.br
\fIdesc\fP Description of the stream\&. 
.br
\fIreplay\fP Specify if the replay is allowed (1 for yes, 0 for no)\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 on success, non-zero value else\&. 
.RE
.PP

.SS "\fBnc_reply\fP* ncntf_subscription_check (const \fBnc_rpc\fP *subscribe_rpc)"

.PP
Check validity of <create-subscription> message\&. This check is done by \fBncntf_dispatch_send()\fP which returns -1 when test does not pass\&. However, it can be sometimes useful to run this test before calling \fBncntf_dispatch_send()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIsubscribe_rpc\fP <create-subscription> RPC\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Reply message to the subscription - ok if tests passed and reply-error with problem description if any of the tests fails\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libnetconf from the source code\&.
